SYSTEM$SEND_EMAIL と SYSTEM$SEND_SNOWFLAKE_NOTIFICATION の違いを整理してみる #SnowflakeDB

SYSTEM$SEND_EMAIL と SYSTEM$SEND_SNOWFLAKE_NOTIFICATION の違いを整理してみる #SnowflakeDB

モダンデータスタック(MDS)

モダンデータスタック(MDS)

#Snowflake
安原朋紀

安原朋紀

facebook logohatena logotwitter logo
Clock Icon2024.08.19

はじめに

Snowflake ではEメールによる通知を送信するためのストアドプロシージャとしてSYSTEM$SEND_EMAIL を使用できます。また、2024年5月のリリースで SYSTEM$SEND_SNOWFLAKE_NOTIFICATION が使用できるようになりました。こちらの機能でも Eメールの送信が可能なため、どのような違いがあるのか、それぞれの概要と合わせて整理しておきたく記事としました。

まとめ

それぞれの主な違いは以下の通りです。

内容 SYSTEM$SEND_EMAIL SYSTEM$SEND_SNOWFLAKE_NOTIFICATION
指定できる通知統合のタイプ EMAILのみ EMAIL以外も指定可能
指定できる通知統合 1回の呼び出しで1種類のみ 1回の呼び出しで複数指定可能
メッセージのタイプ text/plain , text/html text/plain , text/html, application/json

上記の他、SYSTEM$SEND_SNOWFLAKE_NOTIFICATION では以下の特徴があります。

  • 関数に渡す JSON 形式の文字列を生成するためのヘルパー関数の使用が可能
  • EMAIL 通知統合のデフォルト値の上書きが可能

それぞれの特徴とあわせて以降で詳しく見ていきます。

SYSTEM$SEND_EMAIL

SYSTEM$SEND_EMAIL は、同じ Snowflake アカウントのユーザーに対して電子メール通知を送信できるストアドプロシージャです。前提条件として送信先のメールアドレスは、各ユーザーのプロファイルで登録・認証済みのメールアドレスである必要があります。
メール通知送信までの一連の手順は以下にまとまっているので。こちらに沿って確認してみます。

https://docs.snowflake.com/en/user-guide/notifications/email-notifications

メールアドレスの確認

メールを受信するユーザーは、メールアドレスの確認が必要です。Snowsigh からの場合は、以下に記載の手順で実施できます。

https://docs.snowflake.com/ja/user-guide/ui-snowsight-profile#verify-your-email-address

EMAIL 通知統合の作成

メールによる通知統合の作成は以下に記載があります。

https://docs.snowflake.com/en/sql-reference/sql/create-notification-integration-email

こちらはドキュメント記載の例ですが、TYPEオプションの値としてEMAILを指定することで、EMAIL 通知統合として作成できます。

CREATE NOTIFICATION INTEGRATION my_email_int
  TYPE=EMAIL
  ENABLED=TRUE
  ALLOWED_RECIPIENTS=('first.last@example.com','first2.last2@example.com');

また、オプションのALLOWED_RECIPIENTS を指定することで、その統合オブジェクトで通知の送信先に指定できるメールアドレスを限定することが可能です。

メール通知の送信

メール通知の送信にSYSTEM$SEND_EMAILを使用します。関数の構文は以下のようになっており<integration_name>として EMAIL 通知統合を指定します。

SYSTEM$SEND_EMAIL(
  '<integration_name>',
  '<email_address_1> [ , ... <email_address_N> ]',
  '<email_subject>',
  '<email_content>',
  [ '<mime_type>' ] )

SYSTEM$SEND_EMAIL | Snowflake Documentation

以下はドキュメント記載の例ですがこちらを実行してみます。

--EMAIL通知統合の作成
CREATE OR REPLACE NOTIFICATION INTEGRATION my_email_int
  TYPE=EMAIL
  ENABLED=TRUE;

--ストアドプロシージャを実行してメールを送信
CALL SYSTEM$SEND_EMAIL(
    'my_email_int',
    '<確認済みのメールアドレス>',
    'Email Alert: Task A has finished.',
    'Task A has successfully finished.\nStart Time: 10:10:32\nEnd Time: 12:15:45\nTotal Records Processed: 115678'
);

注意点として、通知統合作成時にALLOWED_RECIPIENTSを指定し、ストアドプロシージャ実行時に確認済みのメールアドレスとして、ここで指定した以外のメールアドレスで実行した場合や、そもそもアカウントで認証されていないメールアドレスを指定しストアドプロシージャを実行した場合は下図のようにエラーとなります。

image

問題なく実行されると下図のようなメールが届きます。

image 1

https://docs.snowflake.com/en/user-guide/notifications/email-stored-procedures

HTML 形式も使用できるので、その場合はさいごのオプションでtext/htmlを指定します。※デフォルトはtext/plain

CALL SYSTEM$SEND_EMAIL(
    'my_email_int',
    '<メールアドレス>',
    'Email Alert: Task A has finished.',
    '<html>
        <body>
            <h2 style="color: #2e6c80;">Email Alert: Task A has finished</h2>
            <p>Task A has successfully finished.</p>
            <table border="1" cellpadding="5" cellspacing="0">
                <tr>
                    <th>Start Time</th>
                    <td>10:10:32</td>
                </tr>
                <tr>
                    <th>End Time</th>
                    <td>12:15:45</td>
                </tr>
                <tr>
                    <th>Total Records Processed</th>
                    <td>115,678</td>
                </tr>
            </table>
        </body>
    </html>',
    'text/html'
);

届いたメールの内容

image 2

SYSTEM$SEND_SNOWFLAKE_NOTIFICATION

通知統合はメッセージのタイプごとにTYPEに異なる値を指定します（EMAIL ,QUEUE ,WEBHOOK）。SYSTEM$SEND_SNOWFLAKE_NOTIFICATIONでも通知統合を指定しますが、この際通知統合のタイプとしてEMAIL以外も選択できる点が大きな特徴です。

その他には以下のような特徴があります。

  • 1回の呼び出しで複数の通知統合を指定できる
    • このため、異なるメッセージタイプであっても1回の呼び出しで処理を実行できます
  • EMAIL 通知統合のデフォルト値の上書きが可能
  • メッセージタイプとしてapplication/json を指定可能

通知の送信

はじめに、このストアドプロシージャでの通知の送信について見てみます。以下は EMAIL 通知統合を指定する公式ドキュメントの例を引用したものですが、送信するメッセージと使用する通知統合やその設定を JSON 形式の文字列として渡します。

CALL SYSTEM$SEND_SNOWFLAKE_NOTIFICATION(
   -- Message type and content.
  '{ "text/html": "<p>This is a message.</p>" }',
  -- Integration used to send the notification and values used for the subject and recipients.
  -- These values override the defaults specified in the integration.
  '{
    "my_email_int": {
      "subject": "Status update",
      "toAddress": ["person_a@example.com", "person_b@example.com"],
      "ccAddress": ["person_c@example.com"],
      "bccAddress": ["person_d@example.com"]
    }
  }'
);

JSON 形式での指定なので Notification functions としてJSON 形式の文字列を構築するヘルパー関数をストアドプロシージャ内で指定することができます。

https://docs.snowflake.com/en/sql-reference/functions-notification

上記のクエリをヘルパー関数で構築すると以下のようになります。

CALL SYSTEM$SEND_SNOWFLAKE_NOTIFICATION(
  SNOWFLAKE.NOTIFICATION.TEXT_HTML('<p>a message</p>'),
  SNOWFLAKE.NOTIFICATION.EMAIL_INTEGRATION_CONFIG(
    'my_email_int',
    'Status update',
    ARRAY_CONSTRUCT('person_a@example.com', 'person_b@example.com'),
    ARRAY_CONSTRUCT('person_c@example.com'),
    ARRAY_CONSTRUCT('person_d@example.com')
  )
);

複数の通知統合を指定

複数の統合を使用するには、ARRAY_CONSTRUCT 関数を呼び出し指定したい統合の配列を構築し、その配列をストアドプロシージャの2番目の引数として与えます。

例として以下では、メッセージの通知先として３つの統合オブジェクトを指定しています。my_sns_intでは Amazon SNS に対してEMAIL をエンドポイントとして、my_slack_webhook_intでは Slack に対する通知統合を作成しています。

CALL SYSTEM$SEND_SNOWFLAKE_NOTIFICATION(
  '{"text/plain":"Specify multiple notification integrations"}',
  ARRAY_CONSTRUCT(
    SNOWFLAKE.NOTIFICATION.INTEGRATION('my_sns_int'),
    SNOWFLAKE.NOTIFICATION.INTEGRATION('my_slack_webhook_int'),
    SNOWFLAKE.NOTIFICATION.EMAIL_INTEGRATION_CONFIG('my_email_int','Mail title',ARRAY_CONSTRUCT('<メールアドレス>'))
  )
);

また、メッセージを送信するために使用する通知統合を指定する JSON オブジェクトを返すためにヘルパー関数である SNOWFLAKE.NOTIFICATION.INTEGRATION 関数を使用しています。メール通知の設定については、各オプションを指定できる SNOWFLAKE.NOTIFICATION.EMAIL_INTEGRATION_CONFIG を使用できます。

実行すると下図のようにメッセージを受信できます。※何度か通知を送信しています。

  • メール通知

image 3

  • SNS

image 4

  • Slack

image 5

EMAIL 通知統合のデフォルト値を上書き

EMAIL 通知統合を定義する際、以下のようにその通知統合を使用する場合のデフォルトの件名などを指定できます。

CREATE OR REPLACE NOTIFICATION INTEGRATION my_email_int
  TYPE=EMAIL
  ENABLED=TRUE
  ALLOWED_RECIPIENTS=('<メールアドレス>')
  DEFAULT_SUBJECT = 'Service status';

こちらの通知統合を使用しつつ、以下の内容で通知を送信してみます。EMAIL_INTEGRATION_CONFIGの２つ目の引数が件名を表しますが、NULL を渡すことで除外できます。

CALL SYSTEM$SEND_SNOWFLAKE_NOTIFICATION(
  SNOWFLAKE.NOTIFICATION.TEXT_PLAIN('A message'),
  SNOWFLAKE.NOTIFICATION.EMAIL_INTEGRATION_CONFIG('my_email_int',NULL, ARRAY_CONSTRUCT('<メールアドレス>'))
  );

この場合、下図のようなデフォルトの件名でメールが届きます。

image 6

同じ通知統合で、今度は件名を指定してストアドプロシージャを実行します。

CALL SYSTEM$SEND_SNOWFLAKE_NOTIFICATION(
  SNOWFLAKE.NOTIFICATION.TEXT_PLAIN('A message'),
  SNOWFLAKE.NOTIFICATION.EMAIL_INTEGRATION_CONFIG('my_email_int','件名を上書き', ARRAY_CONSTRUCT('メールアドレス'))
  );

下図の通り、通知統合の設定が上書きされたメールが届きます。

image 7

メッセージタイプとしてapplication/jsonを指定

SYSTEM$SEND_SNOWFLAKE_NOTIFICATIONではメッセージのタイプとしてapplication/jsonを指定できます。この場合も、メッセージの内容は JSON 形式で渡すことになるのでヘルパー関数を使用できます。

CALL SYSTEM$SEND_SNOWFLAKE_NOTIFICATION(
  SNOWFLAKE.NOTIFICATION.APPLICATION_JSON('{ "name": "value" }'),
  SNOWFLAKE.NOTIFICATION.INTEGRATION('my_sns_int')
);

また、メッセージのタイプ毎に以下の関数を使用可能です。

通知の内容

image 8

さいごに

SYSTEM$SEND_EMAILとSYSTEM$SEND_SNOWFLAKE_NOTIFICATIONそれぞれについてまとめてみました。前者はメール通知のためのシンプルな使い方が可能で、後者はメール以外の通知が必要な場合やまとめて複数の通知統合を使用する際に便利です。それぞれ適する場面で使い分けできればと思いました。
こちらの内容が何かの参考になれば幸いです。

Share this article

facebook logohatena logotwitter logo

関連記事

外部ネットワークアクセスで RDS PostgreSQL に IAM認証で接続してみた #SnowflakeDB

外部ネットワークアクセスで RDS PostgreSQL に IAM認証で接続してみた #SnowflakeDB

User avatar
安原朋紀
2024.11.18
AWS PrivateLink を使った Snowflake のアウトバウンド接続を試してみた #SnowflakeDB

AWS PrivateLink を使った Snowflake のアウトバウンド接続を試してみた #SnowflakeDB

User avatar
安原朋紀
2024.11.16
[新機能]Snowflakeでプレビュー機能の有効化・無効化を制御できるシステム関数がリリースされました

[新機能]Snowflakeでプレビュー機能の有効化・無効化を制御できるシステム関数がリリースされました

User avatar
さがら
2024.11.15
[新機能]dbtのdata testで任意の設定をconfigで指定できるようになり、各data testでSnowflakeのウェアハウスを指定できるようになりました

[新機能]dbtのdata testで任意の設定をconfigで指定できるようになり、各data testでSnowflakeのウェアハウスを指定できるようになりました

User avatar
さがら
2024.11.15
Classmethod's white logo
Facebook's logo
X's logo
YouTube's logo

© Classmethod, Inc. All rights reserved.